//! 兼容性 (Compatibility)
//!
//! Rust 有着强大的兼容性保证。Rust 遵循语义化版本控制规范 (SemVer)，
//! 并承诺保持 API 的向后兼容性。这使得 Rust 生态系统能够稳定发展，
//! 同时允许引入新功能和改进。

/// 1. 稳定性保证 (Stability Guarantees)
///
/// Rust 有三个发布渠道：
/// - Stable (稳定版) - 经过充分测试的稳定功能
/// - Beta (测试版) - 即将进入稳定版的功能
/// - Nightly (每日构建版) - 最新的实验性功能
pub fn stability_guarantees() {
    println!("=== 稳定性保证 (Stability Guarantees) ===");

    println!("Rust 的版本策略:");
    println!("1. 主版本号 (Major) - 不兼容的 API 更改（Rust 很少使用）");
    println!("2. 次版本号 (Minor) - 向后兼容的功能新增");
    println!("3. 修订号 (Patch) - 向后兼容的问题修正");

    println!("\n发布渠道:");
    println!("1. Stable - 用于生产环境，功能稳定");
    println!("2. Beta - 测试即将发布的稳定功能");
    println!("3. Nightly - 实验性功能，每日更新");

    println!("\n兼容性保证:");
    println!("- 在同一个主版本内，保证向后兼容");
    println!("- 稳定功能不会在没有明确弃用期的情况下被移除");
    println!("- 编译通过的代码在后续版本中将继续编译通过");
}

/// 2. 条件编译 (Conditional Compilation)
///
/// 使用属性和 cfg 宏来根据编译配置包含或排除代码
pub fn conditional_compilation() {
    println!("\n=== 条件编译 (Conditional Compilation) ===");

    // 根据目标操作系统编译不同代码
    #[cfg(target_os = "linux")]
    fn platform_specific() {
        println!("运行在 Linux 系统上");
    }

    #[cfg(target_os = "windows")]
    fn platform_specific() {
        println!("运行在 Windows 系统上");
    }

    #[cfg(target_os = "macos")]
    fn platform_specific() {
        println!("运行在 macOS 系统上");
    }

    platform_specific();

    // 根据特性标志编译代码
    #[cfg(feature = "enable_debug")]
    println!("调试功能已启用");

    #[cfg(not(feature = "enable_debug"))]
    println!("调试功能未启用");

    // 使用 cfg! 宏在运行时检查配置
    if cfg!(target_arch = "x86_64") {
        println!("运行在 x86_64 架构上");
    } else {
        println!("运行在其他架构上");
    }
}

/// 3. 特性 (Features)
///
/// 使用特性来逐步启用新功能或实验性功能
pub fn features() {
    println!("\n=== 特性 (Features) ===");

    // 在 Cargo.toml 中定义特性:
    // [features]
    // default = []
    // enable_debug = []
    // experimental = ["enable_debug"]

    // 使用特性:
    #[cfg(feature = "enable_debug")]
    fn debug_function() {
        println!("调试功能");
    }

    #[cfg(not(feature = "enable_debug"))]
    fn debug_function() {
        // 空实现或编译期错误
    }

    debug_function();

    println!("特性允许:");
    println!("- 逐步启用新功能");
    println!("- 提供实验性功能");
    println!("- 自定义构建配置");
}

/// 4. 弃用 (Deprecation)
///
/// Rust 提供了处理弃用功能的机制
pub fn deprecation() {
    println!("\n=== 弃用 (Deprecation) ===");

    // 标记函数为弃用
    #[deprecated(since = "1.2.0", note = "请使用 `new_function` 替代")]
    fn old_function() -> i32 {
        42
    }

    fn new_function() -> i32 {
        42
    }

    // 使用弃用函数会产生警告
    let _result = old_function();
    let _result = new_function();

    println!("弃用机制:");
    println!("- #[deprecated] 属性标记弃用项");
    println!("- 提供弃用时间和替代方案");
    println!("- 编译时产生警告");
    println!("- 允许平滑迁移");
}

/// 5. 版本兼容性 (Version Compatibility)
///
/// 管理依赖版本以确保兼容性
pub fn version_compatibility() {
    println!("\n=== 版本兼容性 (Version Compatibility) ===");

    println!("Cargo 版本说明符:");
    println!("1. ^1.2.3 - 兼容 1.2.3 及更高版本，但小于 2.0.0");
    println!("2. ~1.2.3 - 兼容 1.2.3 及更高版本，但小于 1.3.0");
    println!("3. >= 1.2.3 - 大于等于 1.2.3 的任何版本");
    println!("4. = 1.2.3 - 精确匹配 1.2.3 版本");
    println!("5. < 1.2.3 - 小于 1.2.3 的任何版本");

    println!("\n版本策略:");
    println!("- 遵循语义化版本控制");
    println!("- 主版本号变更表示不兼容更改");
    println!("- 次版本号变更表示向后兼容的功能新增");
    println!("- 修订号变更表示向后兼容的问题修正");
}

/// 6. API 演进 (API Evolution)
///
/// 如何在保持兼容性的同时演进 API
pub fn api_evolution() {
    println!("\n=== API 演进 (API Evolution) ===");

    // 1. 添加新函数（安全）
    fn original_function() -> i32 {
        42
    }

    fn new_function() -> i32 {
        42
    }

    // 2. 添加默认参数（通过新函数实现）
    fn function_v1(x: i32) -> i32 {
        x
    }

    fn function_v2(x: i32, y: Option<i32>) -> i32 {
        x + y.unwrap_or(0)
    }

    // 3. 使用特性标志添加实验性功能
    #[cfg(feature = "experimental")]
    fn experimental_function() {
        println!("实验性功能");
    }

    // 4. 弃用旧函数
    #[deprecated(since = "1.1.0", note = "请使用 `improved_function` 替代")]
    fn deprecated_function() -> i32 {
        42
    }

    fn improved_function() -> i32 {
        42
    }

    println!("API 演进策略:");
    println!("- 添加而非修改现有 API");
    println!("- 使用弃用警告平滑过渡");
    println!("- 提供清晰的迁移路径");
    println!("- 保持向后兼容性");
}

/// 7. 平台兼容性 (Platform Compatibility)
///
/// 处理不同平台的兼容性问题
pub fn platform_compatibility() {
    println!("\n=== 平台兼容性 (Platform Compatibility) ===");

    // 检查目标平台
    if cfg!(unix) {
        println!("Unix 系统");
    }

    if cfg!(windows) {
        println!("Windows 系统");
    }

    // 检查目标架构
    if cfg!(target_arch = "x86_64") {
        println!("x86_64 架构");
    } else if cfg!(target_arch = "arm") {
        println!("ARM 架构");
    }

    // 检查指针宽度
    if cfg!(target_pointer_width = "64") {
        println!("64 位平台");
    }

    println!("平台兼容性策略:");
    println!("- 使用条件编译处理平台差异");
    println!("- 提供平台特定的实现");
    println!("- 抽象平台差异");
    println!("- 文档化平台要求");
}

/// 主演示函数
pub fn demonstrate_compatibility() {
    stability_guarantees();
    conditional_compilation();
    features();
    deprecation();
    version_compatibility();
    api_evolution();
    platform_compatibility();
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_stability_guarantees() {
        // 这个测试主要是验证函数能够被调用
        stability_guarantees();
    }

    #[test]
    fn test_conditional_compilation() {
        conditional_compilation();
    }

    #[test]
    fn test_features() {
        features();
    }

    #[test]
    fn test_version_compatibility() {
        version_compatibility();
    }

    #[test]
    fn test_api_evolution() {
        api_evolution();
    }

    #[test]
    fn test_platform_compatibility() {
        platform_compatibility();
    }

    #[test]
    fn test_demonstrate_compatibility() {
        demonstrate_compatibility();
    }
}
